
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
  "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">

<html xmlns="http://www.w3.org/1999/xhtml" lang="zh_Hans">
  <head>
    <meta http-equiv="X-UA-Compatible" content="IE=Edge" />
    <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
    <title>编写文档 &#8212; Django 3.2.6.dev 文档</title>
    <link rel="stylesheet" href="../../_static/default.css" type="text/css" />
    <link rel="stylesheet" href="../../_static/pygments.css" type="text/css" />
    <script type="text/javascript" id="documentation_options" data-url_root="../../" src="../../_static/documentation_options.js"></script>
    <script type="text/javascript" src="../../_static/jquery.js"></script>
    <script type="text/javascript" src="../../_static/underscore.js"></script>
    <script type="text/javascript" src="../../_static/doctools.js"></script>
    <script type="text/javascript" src="../../_static/language_data.js"></script>
    <link rel="index" title="索引" href="../../genindex.html" />
    <link rel="search" title="搜索" href="../../search.html" />
    <link rel="next" title="使 Django 本地化" href="localizing.html" />
    <link rel="prev" title="JavaScript" href="writing-code/javascript.html" />



 
<script src="../../templatebuiltins.js"></script>
<script>
(function($) {
    if (!django_template_builtins) {
       // templatebuiltins.js missing, do nothing.
       return;
    }
    $(document).ready(function() {
        // Hyperlink Django template tags and filters
        var base = "../../ref/templates/builtins.html";
        if (base == "#") {
            // Special case for builtins.html itself
            base = "";
        }
        // Tags are keywords, class '.k'
        $("div.highlight\\-html\\+django span.k").each(function(i, elem) {
             var tagname = $(elem).text();
             if ($.inArray(tagname, django_template_builtins.ttags) != -1) {
                 var fragment = tagname.replace(/_/, '-');
                 $(elem).html("<a href='" + base + "#" + fragment + "'>" + tagname + "</a>");
             }
        });
        // Filters are functions, class '.nf'
        $("div.highlight\\-html\\+django span.nf").each(function(i, elem) {
             var filtername = $(elem).text();
             if ($.inArray(filtername, django_template_builtins.tfilters) != -1) {
                 var fragment = filtername.replace(/_/, '-');
                 $(elem).html("<a href='" + base + "#" + fragment + "'>" + filtername + "</a>");
             }
        });
    });
})(jQuery);(function($) {
    $(document).ready(function() {
        $(".c-tab-unix").on("click", function() {
            $("section.c-content-unix").show();
            $("section.c-content-win").hide();
            $(".c-tab-unix").prop("checked", true);
        });
        $(".c-tab-win").on("click", function() {
            $("section.c-content-win").show();
            $("section.c-content-unix").hide();
            $(".c-tab-win").prop("checked", true);
        });
    });
})(jQuery);</script>
<link rel="stylesheet" href="../../_static/console-tabs.css" type="text/css" />
  </head><body>

    <div class="document">
  <div id="custom-doc" class="yui-t6">
    <div id="hd">
      <h1><a href="../../index.html">Django 3.2.6.dev 文档</a></h1>
      <div id="global-nav">
        <a title="Home page" href="../../index.html">Home</a>  |
        <a title="Table of contents" href="../../contents.html">Table of contents</a>  |
        <a title="Global index" href="../../genindex.html">Index</a>  |
        <a title="Module index" href="../../py-modindex.html">Modules</a>
      </div>
      <div class="nav">
    &laquo; <a href="writing-code/javascript.html" title="JavaScript">previous</a>
     |
    <a href="../index.html" title="Django internals" accesskey="U">up</a>
   |
    <a href="localizing.html" title="使 Django 本地化">next</a> &raquo;</div>
    </div>

    <div id="bd">
      <div id="yui-main">
        <div class="yui-b">
          <div class="yui-g" id="internals-contributing-writing-documentation">
            
  <div class="section" id="s-writing-documentation">
<span id="writing-documentation"></span><h1>编写文档<a class="headerlink" href="#writing-documentation" title="永久链接至标题">¶</a></h1>
<p>我们极其重视文档的一致性和可读性。毕竟，Django 是在需要快速发布新闻的环境下开发的！所以，我们像对待我们的代码一样对待我们的文档：我们期望尽可能频繁地更新它。</p>
<p>一般来说，文档会在以下两种情况时更新：</p>
<ul class="simple">
<li>一般改进：通过更清晰的书写和更多示例，更正、修复文档错误，更好的解释功能。</li>
<li>新特性：自上一个版本发布后，添加到框架中的功能文档。</li>
</ul>
<p>本节介绍文档作者如何以最有用和最不容易出错的方式修改文档。</p>
<div class="section" id="s-getting-the-raw-documentation">
<span id="getting-the-raw-documentation"></span><h2>获得原始文档<a class="headerlink" href="#getting-the-raw-documentation" title="永久链接至标题">¶</a></h2>
<p>Django 文档可在 <a class="reference external" href="https://docs.djangoproject.com/">https://docs.djangoproject.com/</a> 以网页的形式阅读，但我们以一种更灵活的方式编辑它——一系列的文本文件。这些文件位于  Django 的每个发布分支的顶级目录 <code class="docutils literal notranslate"><span class="pre">docs/</span></code> 下。</p>
<p>如果你想开始为我们的文档做贡献，请从源代码库中获取 Django 的开发版本（见 <a class="reference internal" href="../../topics/install.html#installing-development-version"><span class="std std-ref">Installing the development version</span></a>）。开发版有最新、最棒的文档，就像它有最新、最棒的代码一样。在提交者的决定下，我们也会将文档的修正和改进向后移植到最后的发行分支。这是因为让最后一个发行的文档是最新的和正确的是非常有利的（见 <a class="reference internal" href="../../intro/whatsnext.html#differences-between-doc-versions"><span class="std std-ref">版本之间的差异</span></a>）。</p>
</div>
<div class="section" id="s-getting-started-with-sphinx">
<span id="getting-started-with-sphinx"></span><h2>开始使用 Sphinx<a class="headerlink" href="#getting-started-with-sphinx" title="永久链接至标题">¶</a></h2>
<p>Django  的文档使用 <a class="reference external" href="https://www.sphinx-doc.org/">Sphinx</a> 文档系统——基于 <a class="reference external" href="https://docutils.sourceforge.io/">docutils</a>。基本思想是将轻量格式话的纯文本转化为 HTML，PDF 或其它任意输出格式。</p>
<p>要在本地构建文档，请安装 Sphinx：</p>
<div class="console-block" id="console-block-0">
<input class="c-tab-unix" id="c-tab-0-unix" type="radio" name="console-0" checked>
<label for="c-tab-0-unix" title="Linux/macOS">&#xf17c/&#xf179</label>
<input class="c-tab-win" id="c-tab-0-win" type="radio" name="console-0">
<label for="c-tab-0-win" title="Windows">&#xf17a</label>
<section class="c-content-unix" id="c-content-0-unix">
<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">$ </span>python -m pip install Sphinx
</pre></div>
</div>
</section>
<section class="c-content-win" id="c-content-0-win">
<div class="highlight"><pre><span></span><span class="gp">...\&gt;</span> py -m pip install Sphinx
</pre></div>
</section>
</div>
<p>然后从 <code class="docutils literal notranslate"><span class="pre">docs</span></code> 目录下，编译 HTML：</p>
<div class="console-block" id="console-block-1">
<input class="c-tab-unix" id="c-tab-1-unix" type="radio" name="console-1" checked>
<label for="c-tab-1-unix" title="Linux/macOS">&#xf17c/&#xf179</label>
<input class="c-tab-win" id="c-tab-1-win" type="radio" name="console-1">
<label for="c-tab-1-win" title="Windows">&#xf17a</label>
<section class="c-content-unix" id="c-content-1-unix">
<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">$ </span>make html
</pre></div>
</div>
</section>
<section class="c-content-win" id="c-content-1-win">
<div class="highlight"><pre><span></span><span class="gp">...\&gt;</span> make.bat html
</pre></div>
</section>
</div>
<p>编写文档前，你需要阅读 <a class="reference external" href="https://www.sphinx-doc.org/en/master/usage/restructuredtext/index.html#rst-index" title="(在 Sphinx v5.0.0+)"><span class="xref std std-ref">reStructuredText 指引</span></a>。</p>
<p>Your locally-built documentation will be themed differently than the
documentation at <a class="reference external" href="https://docs.djangoproject.com/">docs.djangoproject.com</a>.
This is OK! If your changes look good on your local machine, they'll look good
on the website.</p>
</div>
<div class="section" id="s-how-the-documentation-is-organized">
<span id="how-the-documentation-is-organized"></span><h2>文档是如何组成<a class="headerlink" href="#how-the-documentation-is-organized" title="永久链接至标题">¶</a></h2>
<p>文档被分为以下几个类别：</p>
<ul>
<li><p class="first"><a class="reference internal" href="../../intro/index.html"><span class="doc">教程</span></a> 通过几步手把手的教学帮助读者创建一个小玩意。</p>
<p>教程的目的是帮助读者尽可能早地实现一些有用的东西，以便给他们带来信心。</p>
<p>解释我们要解决的问题的性质，这样读者就能理解我们要实现的目标。不要觉得你需要从解释事情的运作开始 —— 重要的是读者做什么，而不是你解释什么。参考你所做的事情并在事后进行解释可能会有帮助。</p>
</li>
<li><p class="first"><a class="reference internal" href="../../topics/index.html"><span class="doc">主题指引</span></a> 旨在在一个较高的层次介绍一个原则或主题。</p>
<p>链接至参考资料而不要重复它。使用示例时，不要不情愿解释对您而言非常基本的事物——它对别人而言可能需要解释。</p>
<p>提供背景信息有助于新人将主题和他们已知的东西联系起来。</p>
</li>
<li><p class="first"><a class="reference internal" href="../../ref/index.html"><span class="doc">参考指南</span></a> 包含 API 的技术参考。它们描述了 Django 的内部机制的运作，并指导其使用。</p>
<p>让参考资料紧紧围绕着主题。假设读者已经理解了所涉及的基本概念，但需要知道或被提醒 Django 是如何做到的。</p>
<p>参考指南并不是进行一般性解释的地方。如果你发现自己在解释基本概念，你可能想把这些材料移到主题指南中。</p>
</li>
<li><p class="first"><a class="reference internal" href="../../howto/index.html"><span class="doc">操作指南</span></a> 是带领读者完成关键科目步骤的方法。</p>
<p>在指南中最重要的是用户想要实现什么。一个指南应该始终以结果为导向，而不是专注于 Django 如何实现所讨论的内部细节。</p>
<p>这些指南比教程更高级，并假定有一些关于 Django 如何工作的知识。假设读者已经学习了教程，并且毫不犹豫地让读者回到相应的教程，而不是重复同样的材料。</p>
</li>
</ul>
</div>
<div class="section" id="s-writing-style">
<span id="writing-style"></span><h2>书写格式<a class="headerlink" href="#writing-style" title="永久链接至标题">¶</a></h2>
<p>当使用代词指代一个假设的人时，如 “a user with a session cookie”，应使用性别中性的代词（they/their/them）。而不是：</p>
<ul class="simple">
<li>he 或 she……使用 they。</li>
<li>him 或 her... 使用 them。</li>
<li>his 或 her……使用 their。</li>
<li>his 或 hers... 使用 theirs。</li>
<li>himself 或 herself... 使用 themselves。</li>
</ul>
<p>尽量避免使用将任务或操作的难度降到最低的词语，如 “easily”、“simply”、“just”、“merely”、“straightforward” 等等。人们的经验可能与你的期望不符，当他们发现某个步骤并不像暗示的那样 “straightforward” 或 “simple” 时，可能会感到沮丧。</p>
</div>
<div class="section" id="s-commonly-used-terms">
<span id="commonly-used-terms"></span><h2>常用术语<a class="headerlink" href="#commonly-used-terms" title="永久链接至标题">¶</a></h2>
<p>以下是整个文档中常用术语的一些格式指南：</p>
<ul class="simple">
<li><strong>Django</strong> -- 当提及该框架时，大写 Django。它仅在 Python 代码中和 djangoproject.com 徽标中使用小写字母。</li>
<li><strong>email</strong> -- 无连字符。</li>
<li><strong>MySQL</strong>, <strong>PostgreSQL</strong>, <strong>SQLite</strong></li>
<li><strong>SQL</strong> -- 当提及 SQL 时，预期的发音应该是 “Ess Queue Ell” 而不是 “sequel”。因此，在诸如 “Returns an SQL expression” 之类的短语中，“SQL” 前应该使用 “an” 而不是 “a”。</li>
<li><strong>Python</strong> -- 当提及该语言时大写。</li>
<li><strong>realize</strong>, <strong>customize</strong>, <strong>initialize</strong>, etc. -- 使用美式的 “ize” 后缀，而不是 “ise”。</li>
<li><strong>subclass</strong> -- 它是一个没有连字符的单个单词，既作为动词（“子类模型”）又作为名词（“创建子类”）。</li>
<li><strong>Web</strong>, <strong>World Wide Web</strong>, <strong>the Web</strong> -- 指万维网时注意 Web 总是大写。</li>
<li><strong>website</strong> -- 用一个单词表示，不大写。</li>
</ul>
</div>
<div class="section" id="s-django-specific-terminology">
<span id="django-specific-terminology"></span><h2>Django 专用术语<a class="headerlink" href="#django-specific-terminology" title="永久链接至标题">¶</a></h2>
<ul class="simple">
<li><strong>model</strong> -- 它不是大写的。</li>
<li><strong>template</strong> -- 它不是大写的。</li>
<li><strong>URLconf</strong> -- 使用了三个大写字母，在 “conf” 之前没有空格。</li>
<li><strong>view</strong> -- 它不是大写的。</li>
</ul>
</div>
<div class="section" id="s-guidelines-for-restructuredtext-files">
<span id="guidelines-for-restructuredtext-files"></span><h2>reStructuredText 文件语法指南<a class="headerlink" href="#guidelines-for-restructuredtext-files" title="永久链接至标题">¶</a></h2>
<p>这些准则规定了我们的 reST（reStructuredText）文档格式：</p>
<ul>
<li><p class="first">在部分标题中，仅将首字母和专有名词大写。</p>
</li>
<li><p class="first">将文档以 80 个字符宽换行，除非一个代码例子被分割成两行时可读性明显降低，或者有其他好的理由。</p>
</li>
<li><p class="first">在编写和编辑文档时要记住的主要事情是，可以添加的语义标记越多越好。 所以：</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>Add ``django.contrib.auth`` to your ``INSTALLED_APPS``...
</pre></div>
</div>
<p>远没有：</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>Add :mod:`django.contrib.auth` to your :setting:`INSTALLED_APPS`...
</pre></div>
</div>
<p>这是因为 Sphinx 将为后者生成适当的链接，这对读者有很大帮助。</p>
<p>你可以在目标前加一个 <code class="docutils literal notranslate"><span class="pre">~</span></code> （那是一个波浪号）来获得该路径的 “最后一点”。所以 <code class="docutils literal notranslate"><span class="pre">:mod:`~django.contrib.auth</span></code> 将显示一个标题为 “auth” 的链接。</p>
</li>
<li><p class="first">使用 <a class="reference external" href="https://www.sphinx-doc.org/en/master/usage/extensions/intersphinx.html#module-sphinx.ext.intersphinx" title="(在 Sphinx v5.0.0+)"><code class="xref py py-mod docutils literal notranslate"><span class="pre">intersphinx</span></code></a> 来引用 Python 和 Sphinx 的文档。</p>
</li>
<li><p class="first">在文字块中加入 <code class="docutils literal notranslate"><span class="pre">..</span> <span class="pre">code-block::</span> <span class="pre">&lt;lang&gt;</span></code>，使其得到高亮。更倾向于使用 <code class="docutils literal notranslate"><span class="pre">::</span></code> （两个冒号）来自动突出显示。这样做的好处是，如果代码中包含一些无效的语法，它就不会被高亮显示。例如，添加 <code class="docutils literal notranslate"><span class="pre">..</span> <span class="pre">code-block::</span> <span class="pre">python</span></code>，就可以在无效的语法中强制高亮显示。</p>
</li>
<li><p class="first">为了提高可读性，使用 <code class="docutils literal notranslate"><span class="pre">..</span> <span class="pre">admonition::</span> <span class="pre">Descriptive</span> <span class="pre">title</span></code> 而不是 <code class="docutils literal notranslate"><span class="pre">..</span> <span class="pre">note::</span></code>。尽量少使用这些方框。</p>
</li>
<li><p class="first">使用这些标题样式：</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="o">===</span>
<span class="n">One</span>
<span class="o">===</span>

<span class="n">Two</span>
<span class="o">===</span>

<span class="n">Three</span>
<span class="o">-----</span>

<span class="n">Four</span>
<span class="o">~~~~</span>

<span class="n">Five</span>
<span class="o">^^^^</span>
</pre></div>
</div>
</li>
<li><p class="first">使用 <a class="reference external" href="https://www.sphinx-doc.org/en/master/usage/restructuredtext/roles.html#role-rfc" title="(在 Sphinx v5.0.0+)"><code class="xref rst rst-role docutils literal notranslate"><span class="pre">:rfc:</span></code></a> 来引用 RFC，如果可能，尽量链接到相关章节。例如，使用 <code class="docutils literal notranslate"><span class="pre">:rfc:`2324#section-2.3.2`</span></code> 或 <code class="docutils literal notranslate"><span class="pre">:rfc:`Custom</span> <span class="pre">link</span> <span class="pre">text</span> <span class="pre">&lt;2324#section-2.3.2&gt;`</span></code>。</p>
</li>
<li><p class="first">使用 <a class="reference external" href="https://www.sphinx-doc.org/en/master/usage/restructuredtext/roles.html#role-pep" title="(在 Sphinx v5.0.0+)"><code class="xref rst rst-role docutils literal notranslate"><span class="pre">:pep:</span></code></a> 来引用 Python 增强建议（PEP），如果可能的话，尽量链接到相关章节。例如，使用 <code class="docutils literal notranslate"><span class="pre">:pep:`20#easter-egg`</span></code> 或 <code class="docutils literal notranslate"><span class="pre">:pep:`Easter</span> <span class="pre">Egg</span> <span class="pre">&lt;20#easter-egg&gt;`</span></code>。</p>
</li>
<li><p class="first">使用 <a class="reference external" href="https://www.sphinx-doc.org/en/master/usage/restructuredtext/roles.html#role-mimetype" title="(在 Sphinx v5.0.0+)"><code class="xref rst rst-role docutils literal notranslate"><span class="pre">:mimetype:</span></code></a> 来指代一个 MIME 类型，除非在代码示例中引用了这个值。</p>
</li>
<li><p class="first">使用 <a class="reference external" href="https://www.sphinx-doc.org/en/master/usage/restructuredtext/roles.html#role-envvar" title="(在 Sphinx v5.0.0+)"><code class="xref rst rst-role docutils literal notranslate"><span class="pre">:envvar:</span></code></a> 来指代一个环境变量。你可能还需要使用 <a class="reference external" href="https://www.sphinx-doc.org/en/master/usage/restructuredtext/domains.html#directive-envvar" title="(在 Sphinx v5.0.0+)"><code class="xref rst rst-dir docutils literal notranslate"><span class="pre">...envvar::</span></code></a> 来定义一个对该环境变量的文档的引用。</p>
</li>
</ul>
</div>
<div class="section" id="s-django-specific-markup">
<span id="django-specific-markup"></span><h2>Django 特有的标记<a class="headerlink" href="#django-specific-markup" title="永久链接至标题">¶</a></h2>
<p>除了 <a class="reference external" href="https://www.sphinx-doc.org/en/master/usage/restructuredtext/index.html#rst-index" title="(在 Sphinx v5.0.0+)"><span class="xref std std-ref">Sphinx 的内置标记</span></a>，Django 的文档定义了一些额外的描述单元：</p>
<ul>
<li><p class="first">配置：</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="o">..</span> <span class="n">setting</span><span class="p">::</span> <span class="n">INSTALLED_APPS</span>
</pre></div>
</div>
<p>为了连接配置，请使用配置 <code class="docutils literal notranslate"><span class="pre">:setting:`INSTALLED_APPS`</span></code>。</p>
</li>
<li><p class="first">模板标签：</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="o">..</span> <span class="n">templatetag</span><span class="p">::</span> <span class="n">regroup</span>
</pre></div>
</div>
<p>为了链接，请使用 <code class="docutils literal notranslate"><span class="pre">:ttag:`regroup`</span></code>。</p>
</li>
<li><p class="first">模板过滤器：</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="o">..</span> <span class="n">templatefilter</span><span class="p">::</span> <span class="n">linebreaksbr</span>
</pre></div>
</div>
<p>为了链接，请使用 <code class="docutils literal notranslate"><span class="pre">:tfilter:`linebreaksbr`</span></code> 。</p>
</li>
<li><p class="first">字段查询（例如 <code class="docutils literal notranslate"><span class="pre">Foo.objects.filter(bar__exact=whatever)</span></code>）：</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="o">..</span> <span class="n">fieldlookup</span><span class="p">::</span> <span class="n">exact</span>
</pre></div>
</div>
<p>为了链接，请使用 <code class="docutils literal notranslate"><span class="pre">:lookup:`exact`</span></code>。</p>
</li>
<li><p class="first"><code class="docutils literal notranslate"><span class="pre">django-admin</span></code> 管理员命令：</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="o">..</span> <span class="n">django</span><span class="o">-</span><span class="n">admin</span><span class="p">::</span> <span class="n">migrate</span>
</pre></div>
</div>
<p>为了链接，请使用 <code class="docutils literal notranslate"><span class="pre">:djadmin:`migrate`</span></code>。</p>
</li>
<li><p class="first"><code class="docutils literal notranslate"><span class="pre">django-admin</span></code> 管理员命令行选项：</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="o">..</span> <span class="n">django</span><span class="o">-</span><span class="n">admin</span><span class="o">-</span><span class="n">option</span><span class="p">::</span> <span class="o">--</span><span class="n">traceback</span>
</pre></div>
</div>
<p>为了链接，请使用 <code class="docutils literal notranslate"><span class="pre">:option:`command_name</span> <span class="pre">--trackback</span></code> （或者省略 <code class="docutils literal notranslate"><span class="pre">command_name</span></code>，用于所有命令共享的选项，如 <code class="docutils literal notranslate"><span class="pre">--verbosity</span></code>）。</p>
</li>
<li><p class="first">链接到追踪工单（通常为补丁发行说明保留）：</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>:ticket:`12345`
</pre></div>
</div>
</li>
</ul>
<p>Django 的文档使用一个自定义的 <code class="docutils literal notranslate"><span class="pre">console</span></code> 指令，用于记录涉及 <code class="docutils literal notranslate"><span class="pre">django-admin</span></code>、<code class="docutils literal notranslate"><span class="pre">manage.py</span></code>、<code class="docutils literal notranslate"><span class="pre">python</span></code> 等的命令行实例。在 HTML 文档中，它渲染了一个双选项卡 UI，其中一个选项卡显示 Unix 风格的命令提示符，第二个选项卡显示 Windows 提示符。</p>
<p>例如，你可以替换这个片段：</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>use this command:

.. code-block:: console

    $ python manage.py shell
</pre></div>
</div>
<p>为这个：</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>use this command:

.. console::

    $ python manage.py shell
</pre></div>
</div>
<p>请注意两件事：</p>
<ul class="simple">
<li>你通常会替换出现的 <code class="docutils literal notranslate"><span class="pre">..</span> <span class="pre">code-block::</span> <span class="pre">console</span></code> 指令。</li>
<li>你不需要改变代码例子的实际内容。你仍然假设 Unix-y 环境来编写它（即一个 <code class="docutils literal notranslate"><span class="pre">'$'</span></code> 提示符号，<code class="docutils literal notranslate"><span class="pre">'/'</span></code> 作为文件系统路径组件分隔符等等）。</li>
</ul>
<p>上面的例子将呈现一个有两个选项卡的代码示例块。第一个将显示：</p>
<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">$ </span>python manage.py shell
</pre></div>
</div>
<p>与 <code class="docutils literal notranslate"><span class="pre">..</span> <span class="pre">code-block::</span> <span class="pre">console</span></code> 所呈现的内容相比没有变化）。</p>
<p>第二个将显示：</p>
<div class="highlight-doscon notranslate"><div class="highlight"><pre><span></span><span class="gp">...\&gt;</span> py manage.py shell
</pre></div>
</div>
</div>
<div class="section" id="s-documenting-new-features">
<span id="s-id3"></span><span id="documenting-new-features"></span><span id="id3"></span><h2>记录新功能<a class="headerlink" href="#documenting-new-features" title="永久链接至标题">¶</a></h2>
<p>我们对新功能的政策是：</p>
<blockquote>
<div>所有关于新功能的文档都应该以明确指定该功能只在 Django 开发版本中可用的方式来编写。假设文档读者使用的是最新版本，而不是开发版本。</div></blockquote>
<p>我们首选的标记新特性的方法是在特性的文档前加上。&quot;<code class="docutils literal notranslate"><span class="pre">..</span> <span class="pre">versionadded::</span> <span class="pre">X.Y</span></code>&quot;，后面是一个强制性的空行和一个可选的描述（缩进）。</p>
<p>常规改进或应强调的其他 API 更改应使用 &quot;<code class="docutils literal notranslate"><span class="pre">..</span> <span class="pre">versionchanged::</span> <span class="pre">X.Y</span></code>&quot; 指令（与上述 <code class="docutils literal notranslate"><span class="pre">versionadded</span></code> 相同。</p>
<p>这些 <code class="docutils literal notranslate"><span class="pre">versionadded</span></code> 和 <code class="docutils literal notranslate"><span class="pre">versionchanged</span></code> 块应该是 “自包含的”。换句话说，由于我们只在两个版本中保留这些注释，所以最好能够删除注解及其内容，而不必对周围的文本进行重写、重新缩进或编辑。例如，与其把一个新的或改变了的功能的全部描述放在一个块中，不如这样做：</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>.. class:: Author(first_name, last_name, middle_name=None)

    A person who writes books.

    ``first_name`` is ...

    ...

    ``middle_name`` is ...

    .. versionchanged:: A.B

        The ``middle_name`` argument was added.
</pre></div>
</div>
<p>把修改后的注解说明放在一个章节的底部，而不是顶部。</p>
<p>另外，避免在 <code class="docutils literal notranslate"><span class="pre">versionadded</span></code> 或 <code class="docutils literal notranslate"><span class="pre">versionchanged</span></code> 块之外提及 Django 的特定版本。即使在代码块中，这样做也是多余的，因为这些注解分别呈现为 &quot;New in Django A.B:&quot; 和 &quot;Changed in Django A.B&quot;。</p>
<p>如果增加了一个函数、属性等，使用 <code class="docutils literal notranslate"><span class="pre">versionadded</span></code> 注解也是可以的，像这样：</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="o">..</span> <span class="n">attribute</span><span class="p">::</span> <span class="n">Author</span><span class="o">.</span><span class="n">middle_name</span>

    <span class="o">..</span> <span class="n">versionadded</span><span class="p">::</span> <span class="n">A</span><span class="o">.</span><span class="n">B</span>

    <span class="n">An</span> <span class="n">author</span><span class="s1">&#39;s middle name.</span>
</pre></div>
</div>
<p>我们可以删除 <code class="docutils literal notranslate"><span class="pre">..</span> <span class="pre">versionadded::</span> <span class="pre">A.B</span></code> 注解，而不需要在时间上做任何缩进的改变。</p>
</div>
<div class="section" id="s-minimizing-images">
<span id="minimizing-images"></span><h2>最小化图像<a class="headerlink" href="#minimizing-images" title="永久链接至标题">¶</a></h2>
<p>尽可能地优化图像压缩。对于 PNG 文件，使用 OptiPNG 和 AdvanceCOMP 的 <code class="docutils literal notranslate"><span class="pre">advpng</span></code>：</p>
<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">$ </span><span class="nb">cd</span> docs
<span class="gp">$ </span>optipng -o7 -zm1-9 -i0 -strip all <span class="sb">`</span>find . -type f -not -path <span class="s2">&quot;./_build/*&quot;</span> -name <span class="s2">&quot;*.png&quot;</span><span class="sb">`</span>
<span class="gp">$ </span>advpng -z4 <span class="sb">`</span>find . -type f -not -path <span class="s2">&quot;./_build/*&quot;</span> -name <span class="s2">&quot;*.png&quot;</span><span class="sb">`</span>
</pre></div>
</div>
<p>This is based on OptiPNG version 0.7.5. Older versions may complain about the
<code class="docutils literal notranslate"><span class="pre">-strip</span> <span class="pre">all</span></code> option being lossy.</p>
</div>
<div class="section" id="s-an-example">
<span id="an-example"></span><h2>一个例子<a class="headerlink" href="#an-example" title="永久链接至标题">¶</a></h2>
<p>有关如何将它们组合在一起的快速示例，请考虑以下假设示例：</p>
<ul>
<li><p class="first">首先， <code class="docutils literal notranslate"><span class="pre">ref/settings.txt</span></code> 配置文件可能具有如下总体布局：</p>
<div class="highlight-rst notranslate"><div class="highlight"><pre><span></span><span class="gh">========</span>
<span class="gh">Settings</span>
<span class="gh">========</span>

<span class="cp">...</span>

<span class="p">..</span> <span class="nt">_available-settings:</span>

<span class="gh">Available settings</span>
<span class="gh">==================</span>

<span class="cp">...</span>

<span class="p">..</span> <span class="nt">_deprecated-settings:</span>

<span class="gh">Deprecated settings</span>
<span class="gh">===================</span>

<span class="cp">...</span>
</pre></div>
</div>
</li>
<li><p class="first">接下来， <code class="docutils literal notranslate"><span class="pre">topics/settings.txt</span></code> 配置文档可能包含以下内容：</p>
<div class="highlight-rst notranslate"><div class="highlight"><pre><span></span>You can access a :ref:`listing of all available settings
<span class="nt">&lt;available-settings&gt;</span>`. For a list of deprecated settings see
<span class="na">:ref:</span><span class="nv">`deprecated-settings`</span>.

You can find both in the :doc:`settings reference document
<span class="nt">&lt;/ref/settings&gt;</span>`.
</pre></div>
</div>
<p>当我们想链接到另一个文档时，我们使用 <a class="reference external" href="https://www.sphinx-doc.org/en/master/usage/restructuredtext/roles.html#role-doc" title="(在 Sphinx v5.0.0+)"><code class="xref rst rst-role docutils literal notranslate"><span class="pre">doc</span></code></a> 交叉引用元素；当我们想链接到文档中的任意的位置时，请使用 <a class="reference external" href="https://www.sphinx-doc.org/en/master/usage/restructuredtext/roles.html#role-ref" title="(在 Sphinx v5.0.0+)"><code class="xref rst rst-role docutils literal notranslate"><span class="pre">ref</span></code></a> 元素。</p>
</li>
<li><p class="first">接下来，请注意配置的注解方式：</p>
<div class="highlight-rst notranslate"><div class="highlight"><pre><span></span><span class="p">..</span> <span class="ow">setting</span><span class="p">::</span> ADMINS

<span class="gh">ADMINS</span>
<span class="gh">======</span>

Default: <span class="s">``[]``</span> (Empty list)

A list of all the people who get code error notifications. When
<span class="s">``DEBUG=False``</span> and a view raises an exception, Django will email these people
with the full exception information. Each member of the list should be a tuple
of (Full name, email address). Example<span class="se">::</span>

<span class="s">    [(&#39;John&#39;, &#39;john@example.com&#39;), (&#39;Mary&#39;, &#39;mary@example.com&#39;)]</span>

Note that Django will email <span class="ge">*all*</span> of these people whenever an error happens.
See <span class="na">:doc:</span><span class="nv">`/howto/error-reporting`</span> for more information.
</pre></div>
</div>
<p>这标志着下面的标题是配置 <code class="docutils literal notranslate"><span class="pre">ADMINS</span></code> 的 “标准” 目标。这意味着当我谈到 <code class="docutils literal notranslate"><span class="pre">ADMINS</span></code> 时，我可以用 <code class="docutils literal notranslate"><span class="pre">:setting:`ADMINS`</span></code> 来引用它。</p>
</li>
</ul>
<p>基本上，这就是所有东西融合在一起的方式。</p>
</div>
<div class="section" id="s-spelling-check">
<span id="s-documentation-spelling-check"></span><span id="spelling-check"></span><span id="documentation-spelling-check"></span><h2>拼写检查<a class="headerlink" href="#spelling-check" title="永久链接至标题">¶</a></h2>
<p>在你提交你的文档之前，运行拼写检查器是个好主意。你需要先安装 <a class="reference external" href="https://pypi.org/project/sphinxcontrib-spelling/">sphinxcontrib-spelling</a> 。然后从 <code class="docutils literal notranslate"><span class="pre">docs</span></code> 目录下，运行 <code class="docutils literal notranslate"><span class="pre">make</span> <span class="pre">spelling</span></code>。错误的词（如果有的话）以及它们出现的文件和行号将被保存到 <code class="docutils literal notranslate"><span class="pre">_build/spelling/output.txt</span></code>。</p>
<p>如果你遇到假阳性的情况（错误输出实际上是正确的），请采取以下措施之一：</p>
<ul class="simple">
<li>用重音（`）包围内联代码或品牌／技术名称。</li>
<li>查找拼写检查程序发现的同义词。</li>
<li>如果，只是如果，你确定你的单词拼写是正确的——将其加入 <code class="docutils literal notranslate"><span class="pre">docs/spelling_wordlist</span></code> （请保持这个列表以字母顺序排列）。</li>
</ul>
</div>
<div class="section" id="s-translating-documentation">
<span id="translating-documentation"></span><h2>翻译文档<a class="headerlink" href="#translating-documentation" title="永久链接至标题">¶</a></h2>
<p>查看 <a class="reference internal" href="localizing.html#translating-documentation"><span class="std std-ref">本地化 Django 文档</span></a>，如果你想帮助我们将文档翻译成其它语言。</p>
</div>
<div class="section" id="s-django-admin-man-page">
<span id="s-django-admin-manpage"></span><span id="django-admin-man-page"></span><span id="django-admin-manpage"></span><h2><code class="docutils literal notranslate"><span class="pre">django-admin</span></code> 手册页面<a class="headerlink" href="#django-admin-man-page" title="永久链接至标题">¶</a></h2>
<p>Sphinx 可以为 <a class="reference internal" href="../../ref/django-admin.html"><span class="doc">django-admin</span></a> 命令生成一个手册页。这是在 <code class="docutils literal notranslate"><span class="pre">docs/conf.py</span></code> 中配置的。与其他文档输出不同，这个手册页应该包含在 Django 仓库和版本中，作为 <code class="docutils literal notranslate"><span class="pre">docs/man/django-admin.1</span></code>。在更新文档时不需要更新这个文件，因为它作为发行过程的一部分被更新一次。</p>
<p>要生成更新版本的手册，请在 <code class="docutils literal notranslate"><span class="pre">docs</span></code> 目录下运行 <code class="docutils literal notranslate"><span class="pre">make</span> <span class="pre">man</span></code>。新的手册页将写在 <code class="docutils literal notranslate"><span class="pre">docs/_build/man/django-admin.1</span></code>。</p>
</div>
</div>


          </div>
        </div>
      </div>
      
        
          <div class="yui-b" id="sidebar">
            
      <div class="sphinxsidebar" role="navigation" aria-label="main navigation">
        <div class="sphinxsidebarwrapper">
  <h3><a href="../../contents.html">Table of Contents</a></h3>
  <ul>
<li><a class="reference internal" href="#">编写文档</a><ul>
<li><a class="reference internal" href="#getting-the-raw-documentation">获得原始文档</a></li>
<li><a class="reference internal" href="#getting-started-with-sphinx">开始使用 Sphinx</a></li>
<li><a class="reference internal" href="#how-the-documentation-is-organized">文档是如何组成</a></li>
<li><a class="reference internal" href="#writing-style">书写格式</a></li>
<li><a class="reference internal" href="#commonly-used-terms">常用术语</a></li>
<li><a class="reference internal" href="#django-specific-terminology">Django 专用术语</a></li>
<li><a class="reference internal" href="#guidelines-for-restructuredtext-files">reStructuredText 文件语法指南</a></li>
<li><a class="reference internal" href="#django-specific-markup">Django 特有的标记</a></li>
<li><a class="reference internal" href="#documenting-new-features">记录新功能</a></li>
<li><a class="reference internal" href="#minimizing-images">最小化图像</a></li>
<li><a class="reference internal" href="#an-example">一个例子</a></li>
<li><a class="reference internal" href="#spelling-check">拼写检查</a></li>
<li><a class="reference internal" href="#translating-documentation">翻译文档</a></li>
<li><a class="reference internal" href="#django-admin-man-page"><code class="docutils literal notranslate"><span class="pre">django-admin</span></code> 手册页面</a></li>
</ul>
</li>
</ul>

  <h4>上一个主题</h4>
  <p class="topless"><a href="writing-code/javascript.html"
                        title="上一章">JavaScript</a></p>
  <h4>下一个主题</h4>
  <p class="topless"><a href="localizing.html"
                        title="下一章">使 Django 本地化</a></p>
  <div role="note" aria-label="source link">
    <h3>本页</h3>
    <ul class="this-page-menu">
      <li><a href="../../_sources/internals/contributing/writing-documentation.txt"
            rel="nofollow">显示源代码</a></li>
    </ul>
   </div>
<div id="searchbox" style="display: none" role="search">
  <h3>快速搜索</h3>
    <div class="searchformwrapper">
    <form class="search" action="../../search.html" method="get">
      <input type="text" name="q" />
      <input type="submit" value="转向" />
      <input type="hidden" name="check_keywords" value="yes" />
      <input type="hidden" name="area" value="default" />
    </form>
    </div>
</div>
<script type="text/javascript">$('#searchbox').show(0);</script>
        </div>
      </div>
              <h3>Last update:</h3>
              <p class="topless">7月 23, 2021</p>
          </div>
        
      
    </div>

    <div id="ft">
      <div class="nav">
    &laquo; <a href="writing-code/javascript.html" title="JavaScript">previous</a>
     |
    <a href="../index.html" title="Django internals" accesskey="U">up</a>
   |
    <a href="localizing.html" title="使 Django 本地化">next</a> &raquo;</div>
    </div>
  </div>

      <div class="clearer"></div>
    </div>
  </body>
</html>